The Crimson Fields mission Map .src definition
Each CF battle Map starts as an ascii text source (.src) file which is 'compiled' into a 'level' (.lev) file (using a utility called 'cfed' = see my Building new Maps page). When you 'save' your game, CF saves a .lev file.
The map edit utility, CoMET, can (only) open .lev files (although it can 'save as' .src as well as .lev)
The .lev files can be found in your \Program Files\CrimsonFields\levels\ sub-folder (the file names should give you a clue to the 'battle map' names displayed by CF in the Game Type / Maps window)
The map file defines the terrain layout, the initial position of all the opposing forces, 'handicaps' (typically, extra forces for the computer player), narrative text and even a 'link' to other maps in the same campaign.
Maps consist of multiple parts, of which the most important are the Terrain, the Units and 'events'. Terrain tiles are referenced by ID number (= the order in which they are defined in .tsrc). Units are referenced by name and their positions are defined from the 'top left corner' of the map (tile position [0,0]). For details, see below. The definition of [events] = which controls the 'handicaps' as well as timing of things like reinforcements etc. and the 'winning' / 'loosing' conditions - can be found in 'Part 2' (my [Next >>] page)
What's in the map .src ?
The map .src contains a number of sections each starting with a [header]. Definitions are as follows :-
[mission] Defines the basic mission layout
| [mission] | identifies that the mission section follows |
| name = | (n), reference to the 'mission name' text string (1-30 chars) found at end of this file (strings are numbered from 0 up). This is the name that crimson.exe (and CoMET) shows to the user, so should 'match' the map file .src / .lev name for ease of identification |
| mapwidth = | (10-200), the map width in tile hexes |
| mapheight = | (10-200), the map height in tile lines Total map size (width * height) must be less than 32,768 tiles |
| nextmap = | (map name), identifies the name of the next map if this map is part of a campaign (see 'campaign =' later). |
| info = | (n), reference to the 'level information' text string, at end of this map file (strings are numbered from 0 up) |
| skirmish = | (0 | 1), indicates if this map is 'suitable' for '1 on 1 play' (1), or should be played as part of a campaign (0) |
| campaign = | (0 | 1), indicates if the map is part of a campaign (1) or not (0). |
| campaignname = | (-1 | n), reference to the campaign 'name' text string, at end of this file (n) unless none (-1) |
| campaigninfo = | (-1 | n), reference to the campaign 'info' text, at end of this file (n) unless none (-1) |
| players = | 1 or 2 (1 indicates map is suitable for play against the AI) |
| music = | (file name), name of a soundtrack (either MIDI or Ogg Vorbis) to be played (looped) whilst this map is used. If omitted, the default track for Crimson Fields is used. |
| tileset = | (file name), name of the .tiles set (typically, 'tileset = default') When 'compiled' into a .lev, the map ID codes in the [map-raw] will be 'looked up' in the 'tileset' and pointer to the tile icons embedded in the .lev file. If you subsequently rebuild the 'tileset' with new icons, when you open the .lev it will 'pick up' whatever icon is currently found at the 'old' position. | unitset = | (file name), name of the .unit set (typically, 'unitset = default') When complied into a .lev, the Unit names are looked up in the 'unitset' and 'pointers' to the icons embedded in the .lev file. If you subsequently rebuild the 'unitset', the .lev will 'pick up' whatever icon is found at the 'old' position. |
[map-raw] The map for this 'mission'
| [map-raw] | indicates that the map (terrain tile ID codes) follow |
| n,nn,nnn, .. | (Tile ID codes, ..) comma separated. Leading '0's are accepted, spaces are not. The Tile ID list must be exactly (mapwidth) tile ID codes per line, and exactly (mapheight) lines. A 1280x1024 display will show a 27 x 17 map without scrolling |
[player] Defines the players for this 'mission'
| [player] | First player (player1, Brown, FNA) definitions follow |
| name = | (n), reference to the text string (1-20 chars), containing the name of player1 (typically 'Free Nexus Army'), at end of this file (1-30 chars) |
| briefing = | (-1 or n), reference to the 'briefing' text (multi-line paragraph), at end of this file (n), or none (-1) |
| fcolor = | (254,166,4), brown, the foreground color to use for player1 in r,g,b (=brown) |
| bcolor = | (86,54,12), the background color to use for player1 in r,g,b |
Note that the 'fcolor' / 'bcolor' is used ONLY for the player name display, 'turn indicator' and combat 'progress bar'. The unit colours are set by the artwork in CFUnits.bmp
| [player] | Second player (player2, Blue, Empire) settings |
| name = | (n), reference to the text string (1-20 chars), containing the name of player2 (typically 'Empire of Kand'), at end of this file (1-30 chars) |
| briefing = | (-1 or n), reference to the 'briefing' text (multi-line paragraph), at end of this file (n), or none (-1) |
| fcolor = | (0,170,255), blue, the foreground color to use for player2 in r,g,b |
| bcolor = | (2,38,92), the background color to use for player2 in r,g,b |
[unit] Defines the units deployed on this mission map
| [unit] | The settings for a unit follows. There will be multiple [unit] definitions, one for every unit to be deployed on the map (or starting in a building or carried in a transporter) |
| type = | (unit name), a valid unit name, as found in the .usrc file originally used to build the 'unitset' referenced above Note that when the mission .src is compiled to a .lev file, the unit names are replaced with 'icon numbers' (eg. a North facing Infantry unit for player1 becomes 'icon 0' from the CFUnits.bmp) |
| player = | (1 | 2), used to choose the unit icon, player1, brown (1) or player2, blue (2) There are no 'neutral' units as such, however units garrisoned in a neutral building can not be seen until that building is captured by one of the players (at which point the units are set to that players colours) |
| id = | (0-10000), unique unit identifier. Does not have to be sequential |
| pos = | (X tile)/(Y row), location of the unit on the map. If there is a building or transporter at that location, the unit will start in it (the transports must be defined before their contents). Map tiles are numbered starting at 0/0, the top left hand corner. Units in a 'neutral' building will take on the colours of the player that captures that building |
| size = | (1-6), unit 'strength'. Defaults to 6 (undamaged). |
| xp = | (0-6), unit 'experience level'. Defaults to 0 (no experience). |
| face = | (0-5), direction the unit is facing. Directions are numbered clockwise from North (0) to Northwest (5). Defaults are North (0) facing for (brown) units controlled by player 1, and South (3) for (blue) player 2. Thus new Maps should be laid out with player 1 attacking North, up the map, whilst player 2 will be attacking South, down the map. |
| crystals = | (n), the amount of 'crystals' carried (default 0). Valid only if this unit is defined (in unitset) as a transporter, |
[building] Defines the buildings deployed on this mission map
| [building] | Indicates that a Building definition follows |
| pos = | (X tile)/(Y row), location of the building entrance on the map (mandatory) |
| id = | (0-10000), unique unit identifier |
| player = | (0 | 1 | 2), the building 'owner', none=neutral (0), player 1 (1) or player 2 (2). The Building icon is defined in the [map-raw] section (which determines it's color etc.) Units in a neutral building can not be moved by either player until the building is 'captured'. |
| type = | (depot | workshop | factory), the 'type' of building. A building can have multiple 'type =' definitions. In addition to these types, a building which produces crystals is (automatically) called a 'Mine' |
| depot | storage warehouse only (this is the default) |
| workshop | units can be 'repaired' in the building |
| factory | new units can be 'built' in this building |
| name = | (n), reference to the building name text string (which must be 1-30 characters) |
| mining = | (0-1000), amount of crystals the building will produce for a player each turn. Default 0. If given, implies building type Mine. Neutral buildings do not start producing crystals until captured |
| capacity = | (0-10000), maximum amount of crystals that can be stored. Defaults to 1000. |
| crystals = | (0-capacity), amount of crystals 'in stock'. Defaults to 0. |
| factory = | (unit name), name of a unit that can be 'built' here. A building can have multiple 'factory =' definitions. If factory = appears, this implies a building type = factory. |
| minweight = | (0-99), weight of the smallest unit allowed to enter the building. Defaults to 0. |
| maxweight = | (0-99), weight of the heaviest unit allowed to enter the building. Defaults to 99. |
[event] Defines each 'event' for this mission
Most 'missions' will have dozens of 'events' (in theory, you could have up to 10,000 !). At the very least, the mission must have sufficient 'event' definitions to set the 'win' conditions for each player
Events are so key to how the map plays that I've moved the definitions to their own page (see Next >> )
[message] Defines the messages for this mission
| [messages(language)] | Start of the message text (in the defined language). Messages are auto-numbered starting at 0. Each language section must contain the same number of messages |
| some arbitrary text | Free form text for message (id 0), including 'blank' lines for paragraph spacing |
| % | the message separator |
| some more text | more free form text, including 'blank' lines for paragraph spacing |
| % | the message separator |
| ... | and so on |
| [/messages] | End of the message section for (lang) |
What's with the 'messages' ?
The [messages(language)] section contains all the text used within the scenario, from the 'title' to players & building 'names' along with the 'briefings' and the 'victory' / 'defeat' messages etc. Messages are separated by the '%' symbol
Messages are automatically assigned 'reference names' (numbers) by their order .. the first message is '0' and is (typically) the [Mission], 'name = 0'. In a standard map, the [message] section starts with the Scenario name, then the 'mission details', Player 1 name, Player 2 name, the names of the buildings and finally the 'player briefings'.